AWS CodeDeploy の AppSpec を読み解く

諏訪悠紀

2014.11.17

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

AppSpec

AppSpec は AWS CodeDeploy (以下、CodeDeploy) で実行するデプロイ処理の内容です。デプロイでどのようなことを処理させるか、具体的な内容を記述していく YAML フォーマットで構成されたファイルです。 CodeDeploy を利用する上で、AppSpec でどのような設定を記述するかがとても重要になってきます。

ということで、本記事ではこちらのドキュメントを意訳していきたいと思います。

はじめに

Application Specification File (AppSpec file) は、CodeDeploy があなたの EC2 インスタンスに対して、Amazon S3 または GitHub にあるアプリケーションのリビジョンをどのようにインストールするか決定する、YAML フォーマットのファイルです。また同様に、デプロイの様々なライフサイクルイベントをフックして処理を実行するか決定します。

AppSpec ファイルの名前は必ず appspec.yml とし、ルートディレクトリに配置しておかなればいけません。この要件を満たしていない場合、デプロイは失敗します。また、AppSpec ファイルが存在する場合は、これを含めたデプロイ用のコンテンツを .zip (Windows Server 以外は .tar および .tar.gz も可能) 形式の圧縮ファイルにすることができます(詳しくは Prepare a Revision を参照)。

ファイルの構造

AppSpec ファイルは次のように構成します。

version: 0.0
os: operating-system-name
files:
  source-destination-files-mappings
permissions:
  permissions-specifications
hooks:
  deployment-lifecycle-event-mappings

version

オプション。AppSpec ファイルのバージョンを指定します。デフォルトは 0.0 です。

2015/10/03 修正アプリのバージョンではなく、正しくは AppSpec のバージョンでした。誤った情報であったこと、お詫び申し上げます。ご指摘いただきました takus 様、ありがとうございました！

ちなみに、小数点は1つしか付けることができないと思われます。1.0.0 のような形式でデプロイしたところエラーが発生しました。

os

インストール先の Amazon EC2 インスタンスの OS を指定します。Amazon Linux または Ubuntu Server の場合は linux、Windows Server の場合は windows を指定します。

files

CodeDeploy から EC2 インスタンスにインストールするファイルまたはディレクトリを指定します。アプリケーションのリビジョン内のファイルまたはディレクトリを、インスタンス上の特定の場所にコピーします。source と destination のペアで設定します。複数指定可能です。

source はリビジョンからコピーするファイルまたはディレクトリを指定します。次のような形式を指定できます。なお、すべてリビジョンのルートからの相対パスとして扱われます。

ファイル名を指定した場合、対象のファイルをコピーします。
ディレクトリ名を指定した場合、対象のディレクトリとディレクトリ内の全てのファイルをコピーします。
/ を指定した場合、リビジョンの全てのファイルおよびディレクトリをコピーします。

destination はコピーするファイルの配置場所を絶対パスで指定します。

次の例では、config.txt ファイルを /webapps/Config ディレクトリに、source ディレクトリを /webapps/myApp ディレクトリにコピーしています。

files:
   - source: Config/config.txt
     destination: /webapps/Config
   - source: source
     destination: /webapps/myApp

permissions

files セクション内に記述されたファイルに、どのようなパーミッションを適用するか設定するセクションです。オプションなので、設定しなくても問題ありません。現在はAmazon Linux または Ubuntu Server のみで適用されます。

object

必須。パーミッションを適用する対象として、コピーされたファイルまたはディレクトリを指定します。複数指定可能です。

pattern

オプション。ディレクトリに対して、ディレクトリ内のどのようなファイルに適用するかパターンを指定します。** または pattern が指定されていない場合、ディレクトリ内の全てのファイル・ディレクトリに適用します。

except

オプション。例外として除外するファイルのパターンを指定します。

owner

オプション。適用するファイル・ディレクトリの所有者を指定します。指定しない場合、元のファイルまたはディレクトリに適用されたすべての既存の所有者が維持されます。

group

オプション。適用するファイル・ディレクトリの所有グループを指定します。指定しない場合、元のファイルまたはディレクトリに適用されたすべての既存の所有グループが維持されます。

mode

オプション。適用するファイル・ディレクトリのパーミッションのモードを整数値で指定します。例えば 644 を指定した場合、オーナーは読み書き可能、グループ・すべてのユーザーは読み取り専用になります。指定されていない場合、元のファイルまたはディレクトリに適用されたパーミッションのモードが維持されます。

acls

オプション。適用するファイル・ディレクトリの Access Control List (ACL) を文字列で指定します。例えば u:bob:rw を指定した場合、bob というユーザーに読み書き権限を付与します。複数の ACL を指定可能です。指定されていない場合、元のファイルまたはディレクトリに適用されたすべての既存の ACL が維持されます。また、これらは既存の ACL を置き換えます。

無名ユーザー、無名グループ、またはその他の類似 ACL を設定すると、デプロイが失敗します。代わりに mode を使用しましょう。

context

オプション。適用するファイル・ディレクトリのセキュリティ関連コンテキストを指定します(SELinux が有効なマシンの場合)。user, type, range を SELinux の定義に基づき指定します。指定されていない場合、元のファイルまたはディレクトリに適用されたセキュリティ関連コンテキストが維持されます。詳しくはこちらを参照してください。

type

オプション。適用する対象がファイルまたはディレクトリか指定します。ファイルの場合は file、ディレクトリの場合は directory を指定します。指定しない場合、すべてのファイル・ディレクトリが対象になります。

hooks

デプロイのライフサイクルイベントをフックして差し込む1つ以上のスクリプトを指定します。hooks セクションは、何らかの処理を追加したい場合のみ指定します。ライフサイクルイベントは次のとおりです。フック可能なイベントと、フック不可能なイベントに分けられます。

ApplicationStop - 前回のリビジョンのシャットダウンが開始したとき(フック可能)。
DownloadBundle - AWS CodeDeploy Agent がリビジョンを /opt/codedeploy-agent/deployment-root/deployment-group-id/deployment-id/deployment-archive (Windows Server の場合は C:\ProgramData\Amazon\CodeDeploy\deployment-group-id\deployment-id\deployment-archive) にコピーしたあと(フック不可能)。
BeforeInstall - AWS CodeDeploy が files セクションで指定された場所にファイルをコピーする前(フック可能)。
Install - AWS CodeDeploy が files セクションで指定された場所にファイルをコピーするとき(フック不可能)。
AfterInstall - AWS CodeDeploy が files セクションで指定された場所にファイルをコピーした後(フック可能)。
ApplicationStart - アプリケーションのリビジョンが開始する直前(フック可能)。
ValidateService - サービスの検証が終わった後(フック可能)。

ライフサイクルイベントをフックしたい場合は、hooks セクション内に上記いずれかのライフサイクルイベント名を以下の要素を含めて記述します。

location

必須。実行したいシェルスクリプトファイルの場所を指定します。

timeout

オプション。シェルスクリプト実行時のタイムアウト時間を秒単位で指定します。指定された時間を超過した場合、デプロイエラーとなり処理が中断されます。デフォルト値は1,800秒(30分)です。

runas

オプション。シェルスクリプトの実行ユーザーを指定します。デフォルトは AWS CodeDeploy Agent を実行しているユーザーです。AWS CodeDeploy はパスワードを保存しないため、指定したユーザーにパスワードが設定されているとデプロイエラーとなり処理が中断されます。このオプションは Amazon Linux または Ubuntu Server のみ指定可能です。

hooks セクションの例は以下の通りです。以下の例では、AfterInstall (指定したファイル・ディレクトリを特定のディレクトリにコピーした後)のイベントをフックし、RunResourceTests.sh というシェルスクリプトファイルを実行します。タイムアウトは180秒と指定されているため、処理が3分以上経過したらデプロイエラーとなります。

hooks:
   AfterInstall:
     - location: Scripts/RunResourceTests.sh
       timeout: 180

まとめ

AppSpec は CodeDeploy の要です。適切な AppSpec を書いて、良い CodeDeploy ライフを送りましょう！

参考

AWS CodeDeploy AppSpec File Reference | AWS Documentation